home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / PASCAL / 0826.ZIP / TREF2D.ARC / T-REFCH3.DOC < prev    next >
Text File  |  1987-09-20  |  16KB  |  397 lines
  1.  
  2.  
  3.  
  4.                     Chapter III - The Cross Reference Lister
  5.  
  6.      This  chapter deals primarily with the Cross Reference  Listing  program.
  7. However,  before  getting  into the details of the Reference  Lister,  several
  8. important definitions need to be made to prevent any confusion. Once the terms
  9. used in this chapter are presented, we will present an in-depth description of
  10. the Cross Referencer and its print format.
  11.  
  12. System Identifiers:
  13.  
  14.      Like  most  compilers,  Turbo  Pascal has defined a  set  of  identifiers
  15. already declared under the IBM-PC version.   Often called Standard Identifiers
  16. or System Identifiers,  they include Constants (i.e.,  Blue and  Co80),  Types
  17. (i.e., Integer, Real, Byte, String, and Char), Variables (i.e., Mem and MemW),
  18. Procedures (i.e., Textcolor, Substr, and Window), and Functions (i.e., WhereX,
  19. Copy,  Cos,  and Random).  T-Ref has "pre-declared" the complete list of Turbo
  20. system  identifiers (up through Version 3.01) for referencing and they may  be
  21. included  in the cross reference listing if so desired.   Appendix A gives the
  22. entire list of system defined (standard) identifiers.
  23.  
  24. Data Types:
  25.  
  26.      There  are  three general catagories of data types  in  Pascal:  scalars,
  27. structured types,  and pointers.  Scalars include the standard scalar types as
  28. noted above (Integer,  Byte,  Real,  Boolean,  String,  and Char) and extended
  29. scalar  types  (Subranges  and User-Defined Scalars).   Structured  types  are
  30. arrays,  records,  sets,  and files.   Finally, pointers are address values to
  31. variables of the other data types.
  32.  
  33. Basic Types:
  34.  
  35.      Basic  types,  not to be confused with data types,  are the types of  the
  36. identifiers.   Basic types include Labels, Constants, Types, Variables, Proce-
  37. dures,  and  Functions.   The best way to prevent confusion between these  and
  38. data  types is by noting that most basic types have an associated  data  type.
  39. For example,  the basic type 'Function' may have a data type of Integer.   The
  40. basic  type 'Constant' may have a basic type of Char.   However,  basic  types
  41. Labels,  Procedures, and untyped formal parameters are the only ones that have
  42. an undefined data type.
  43.  
  44.      Labels  do  not necessarily have to be identifiers,  but may  be  integer
  45. numbers as well.  These are handled appropriately by T-Ref.
  46.  
  47.      User  defined  scalar  values are considered  constants  by  T-Ref.   For
  48. example, in the following declaration:
  49.  
  50.       TYPE DAY_OF_WEEK = (SUN,MON,TUE,WED,THU,FRI,SAT);
  51.  
  52. the identifiers SUN, MON, ..., SAT are considered of basic type Constant, even
  53. though the identifier DAY_OF_WEEK is of basic type Type.
  54.  
  55.      All  formal parameter identifiers are considered a special  extension  of
  56. the  basic type Variable.   Therefore,  when Variables are listed in the cross
  57. reference, formal parameter identifiers are included.
  58.  
  59.  
  60.  
  61.                                11
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.      The program name,  when a program head is given,  does not actually  fall
  72. into  any  of  the basic types listed above;  however,  rather than  having  a
  73. separate field for a cross reference of the program name,  it is considered by
  74. T-Ref as a Procedure type with no references other than its declaration.
  75.  
  76. Now for the Cross Reference Lister:
  77.  
  78.      The Cross Reference Lister,  when activated ("ON"),  gives a cross refer-
  79. ence listing of the specified types of identifiers.   Selection of identifiers
  80. is determined by basic type in the following fashion:
  81.  
  82.      Each of the basic types have two fields on the screen:  a scope field and
  83. a  usage  field  (see Figure 1).   The scope field is used  to  determine  the
  84. selection  of  identifiers  based upon whether they are  declared  within  the
  85. system  (system defined or "SysDf") or within the program (program defined  or
  86. "PrgDf").   The  "All" setting is used to select all identifiers of that basic
  87. type.   The "None" setting tells the program to skip listing any identifier of
  88. that basic type.
  89.      The  usage field is used to determine the selection of identifiers  based
  90. upon  whether or not they have been referenced within the program (other  than
  91. in  their  declarations).   The  "Used" setting will select for  listing  only
  92. identifiers  of  that basic type that were actually used within  the  program.
  93. The  "Unused"  setting selects only those identifiers not referenced  anywhere
  94. within  its  scope.  The "All" setting selects  identifiers declared  of  that
  95. basic type irregardless of their use.
  96.  
  97.      The  Cross Reference Lister  is activated by positioning the cursor  over
  98. the  'Cross  Reference' field and striking the space bar until the  word  "On"
  99. appears within the cursor.   To deactivate the cross reference lister, hit the
  100. space bar again and the word "Off" will appear.   Note that the same procedure
  101. here  is used to activate the cross reference lister as in the  source  lister
  102. described in chapter II above.  Like the  source lister,  the nine fields that
  103. appear  on  the  screen directly below the 'Cross Reference' field  relate  to
  104. specific information about what identifiers are to be included or not included
  105. in the cross reference listing, as well as setting a header and paging.  These
  106. fields  are  updated in the same manner as those fields in the  source  lister
  107. area:  by  placing the block cursor over the field and striking the space  bar
  108. until the desired parameter appears within the cursor.
  109.      Since  we have already defined the parameters that appear in  the  fields
  110. 'Labels', 'Constants', 'Types', 'Variables', 'Procedures', and 'Functions', we
  111. will  not pursue this any further except to say that the 'Labels' field has  a
  112. restricted set of values for its scope field: "PrgDf" and "None".  This is due
  113. to  the fact that Turbo has no System Defined labels.   No other  restrictions
  114. apply to any of these fields.
  115.  
  116.      The  'Header' field operates in exactly the same fashion as the  'Header'
  117. field within the source lister area.   When it is activated ("On"), the header
  118. that  was created using the F4 function key will be printed at the top of each
  119. page of cross reference output.  The header can be from two to five lines long
  120. and  each  line can be up to 75 columns in length.   Again,  if  a  header  is
  121. printed, the program will automatically buffer 3 blank lines before the header
  122. and 2 blank lines after the header.
  123.  
  124.      The  'Page Numbering' field also operates like the field of the same name
  125. within the source lister area.   The number of lines per page is set by the F6
  126.  
  127.  
  128.                                12
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137. function key and is the same value used for paging the source listing output.
  138.  
  139.      The  'Include File' field is used to tell the program whether or  not  to
  140. print  files  made  available to the Turbo compiler through the  include  file
  141. compiler directive.   When activated ("Yes"),  include files are automatically
  142. parsed  for cross referencing all identifiers within the  files  (declarations
  143. and uses).   The OPTIONAL setting ("Opt") allows you to selectively choose the
  144. files to be included in the cross referencing process.  If one of the 'Include
  145. File'  fields (either for the source lister or the cross reference lister)  is
  146. activated and the other is not,  the program will take the appropriate actions
  147. to perform only the operations on the include file needed.
  148.  
  149. Interpreting the Cross Reference listing:
  150.  
  151.      There are three parts to the cross reference listing: an identifier cross
  152. reference listing, a procedure/function map listing (table of contents), and a
  153. basic and data types count listing.
  154.  
  155. A.  Identifier Cross Reference Listing:
  156.  
  157.      Each  identifier cross referenced is listed in alphabetical order and has
  158. the following format.   The first two lines of a cross reference entry has the
  159. following format:
  160.  
  161. Name................         Basic-Type              Data-Type
  162.   Declared on line  LLLL:SSSS   within Procedure-Name...... (LVL)
  163.  
  164. where Name is the name of the identifier (20 characters long),  Basic-Type  is
  165. the basic type,  Data-Type is the data type, LLLL:SSSS is the line number (and
  166. possibly the include file's subline number) of the declaration, Procedure-Name
  167. is the procedure or function name that the identifier was declared within  (up
  168. to  20  characters  long),  and LVL is the lexical level of the  procedure  or
  169. function within the program.
  170.      If the identifier was not declared within the source code (as is the case
  171. when  cross referencing a portion of a program or a library or procedures that
  172. reference identifiers in other portions of the program),  then the second line
  173. rather reads:
  174.  
  175.   "Not declared within the scanned source."
  176.  
  177.      The basic type field will be one of the following:
  178.  
  179.      "Undefnd" - Signifies the  use of an undeclared identifier  found  during
  180.                  the parse.
  181. Labels:
  182.      "Label  " - Labels
  183.  
  184. Constants:
  185.      "Constnt" - Constants
  186.      "ScalVal" - Scalar Values
  187.      "Typed C" - Typed Constants
  188.  
  189. Types:
  190.      "Type   " - Types
  191.  
  192.  
  193.  
  194.                                13
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203. Variables:
  204.      "Var    " - Variables
  205.      "FrmParm" - Formal Parameters (considered a Variable)
  206.      "VarParm" - Formal Variable Parameters (considered a Variable)
  207.      "Rec Fld" - Record Fields (considered a Variable)
  208.      "Rec Tag" - Record Fields declared as Record Tags (considered a Variable)
  209.  
  210. Procedures:
  211.      "Program" - Program name
  212.      "Procedr" - Procedures
  213.  
  214. Functions:
  215.      "Functn " - Functions
  216.  
  217. The data type field will be one of the following:
  218.  
  219.      "Undefnd"  - Signifies the use of an undeclared identifier  found  during
  220.                  the parse, or an Untyped Formal Parameter
  221.      "Integer" - Integer scalars
  222.      "Byte   " - Byte scalars
  223.      "Real   " - Real scalars
  224.      "Boolean" - Boolean scalars
  225.      "String " - String scalars
  226.      "Char   " - Character scalars
  227.      "Scalar " - User Defined Scalars
  228.      "Range  " - Subranges
  229.      "Record " - Structured Type Records
  230.  
  231. and  may  be  preceeded  by some combination of the  following  to  signify  a
  232. structured data type:
  233.  
  234.      "Absolute Addr" - The Variable is located at a specific address
  235.      "File of"       - The Type or Variable is of type File
  236.      "Set of"        - The Constant, Type, or Variable is of type Set
  237.      "Pointer to"    - The Type or Variable is of type Pointer
  238.  
  239. For  example,  "Absolute Addr Set of Scalar" means the data type of the ident-
  240. ifier is a set of type scalar and is at a specific address in memory.
  241.  
  242.      The  third  line of the reference,  if the identifier is  not  referenced
  243. within the scanned source code (other than its declaration), will be:
  244.  
  245.   "<<< Identifier not referenced. >>>"
  246.  
  247. If  the identifier has been referenced (other than its  declaration),  then  a
  248. sequence of references are printed.
  249.      First, a header for the references is printed describing the procedure or
  250. function the reference took place:
  251.  
  252.   "Referenced within" Procedure-Name......:
  253.  
  254. followed  by  an ordered list of the lines that identifier was referenced  on.
  255. The  numbering  is in the same format as the declaration line  number  format:
  256. LLLL:SSSS.
  257.      An  asterisk  ("*") just before the line number means the identifier  was
  258. explicitly set to a value on that line of code.  An ampersand ("&") means  the
  259.  
  260.  
  261.                                14
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. same thing, except that the identifier was set at a lexical (procedural) level
  269. BELOW the level of its declaration.  An "L" signifies the variable was used as
  270. a loop variable in a FOR statement.
  271.      Here,  'explicitly  set' means that the variable or function was set with
  272. a  <variable> := <expression> statement,  and does not take into consideration
  273. setting  the  identifier  through the use of procedure or  function  parameter
  274. passing.
  275.  
  276.      In  addition,  the  referencer  analyzes the code to  provide  additional
  277. information:
  278.  
  279.      a.  For procedures and functions, a check is made to determine whether it
  280. is recursive.  If so, it is noted in the listing.
  281.      b.  Overlay and external procedures and functions are noted.
  282.      c.   For  functions  and variable formal parameters,  if they  are  never
  283. explicitly set in the code,  a warning to this effect is printed.   Note  this
  284. does  not  necessarily reflect an error,  since these identifiers may  be  set
  285. through other means.
  286.      d.   For  formal  parameters (not variable formal  parameters)  that  are
  287. explicitly set in the code,  a warning is printed.   This may be an indication
  288. that it should be a variable formal parameter.
  289.  
  290.      At  this  point,  it must be noted that record types and  variables  (and
  291. their  associated  record fields) are a special case and are not handled  pre-
  292. cisely the same as other data types.  This comes about primarily because it is
  293. possible to have (and is often the case,  rather than the exception) more than
  294. one  record variable with the same structure and therefore with precisely  the
  295. same  record field identifiers.   If a record field identifier were listed  as
  296. shown  above,  it  would be impossible without inspection to  determine  which
  297. record variable the reference was associated with.
  298.      Therefore,  references  to  a specific record field are printed  directly
  299. under  all record identifiers containing that field in its  structure.   Cross
  300. references to that field then only include those that pertain specifically  to
  301. the record identifier being listed.
  302.      For example, suppose a record structure type were created:
  303.  
  304.   TYPE
  305.     REC_STRUCT = RECORD
  306.      A,B : BYTE;
  307.     END;
  308.  
  309. and two different record variables were declared from this type:
  310.  
  311.   4  VAR
  312.   5    REC_A, REC_B : REC_STRUCT;
  313.  
  314. Now suppose the following code is implemented:
  315.  
  316.  35   WITH REC_A DO A := 1;
  317.  36   WITH REC_B DO A := 0;
  318.  
  319. where  35  and 36 refer to the line numbers.   Then,  a portion of  the  cross
  320. reference listing would look like this:
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                15
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335. REC_A         Var              Record
  336.   Declared on line    5     within PROGRAM (1)
  337.   Referenced within PROGRAM:
  338.       35       *   35
  339.  
  340.      Record field: A                      Byte
  341.      Referenced within PROGRAM:
  342.   *   35
  343.  
  344.      Record field: B                      Byte
  345.      << Identifier not referenced. >>
  346.  
  347. REC_B         Var              Record
  348.   Declared on line    5     within PROGRAM (1)
  349.   Referenced within PROGRAM:
  350.       36       *   36
  351.  
  352.      Record field: A                      Byte
  353.      Referenced within PROGRAM:
  354.   *   36
  355.  
  356.      Record field: B                      Byte
  357.      << Identifier not referenced. >>
  358.  
  359. Here,  record  field A has been broken out into its individual references  and
  360. therefore, it can be seen which reference goes with which record variable.
  361.      Also note that  REC_A and  REC_B show two  references.  The first are the
  362. references  of the  identifiers  within the  WITH clauses; the  second are the
  363. references of record fields BELONGING to these identifiers.   The asterisk (*)
  364. shows where the identifiers were set to some value.
  365.  
  366. B.  Procedure/Function Mapping:
  367.  
  368.      The  second  part  of  the cross reference lister is a  printout  of  all
  369. procedures and functions declared within the parse, along with the line number
  370. of  the declaration.   The names are indented according to the lexical  (proc-
  371. edural) level,  and overlay and external procedures/functions are again noted.
  372. This portion of the listing is excellent for getting a general layout (a table
  373. of contents) of a program or library.
  374.  
  375. C.  Basic and Data Type Count Listing:
  376.  
  377.      Finally,  the  cross  reference lister prints a summation  of  the  total
  378. number of lines parsed,  the total number of identifiers cross referenced, and
  379. a  break-out of the identifier count by basic type and data  type.   Remember,
  380. "Undefnd"  basic  types are those identifiers parsed but were never  declared.
  381. (Also remember, untyped formal parameters, labels, procedures, and the program
  382. name have no data type associated with them and therefore will not be included
  383. in the data type totals.)
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                16
  393.  
  394.  
  395.  
  396.  
  397.